
<html><HEAD>
<LINK REL=STYLESHEET HREF="default.css" TYPE="text/css">
<TITLE>
Using the ASA MobiLink synchronization wizard</TITLE>
</HEAD>
<BODY>

<!-- Header -->
<p class="ancestor" align="right"><A HREF="pbugp148.htm">Previous</A>&nbsp;&nbsp;<A HREF="pbugp150.htm" >Next</A>
<!-- End Header -->
<A NAME="BDCGFFCA"></A><h1>Using the ASA MobiLink synchronization wizard</h1>
<A NAME="TI4509"></A><h4>About MobiLink </h4>
<A NAME="TI4510"></A><p>MobiLink is a session-based synchronization system that allows
two-way synchronization between a main database, called the consolidated
database, and multiple remote databases. The ASA MobiLink Synchronization
wizard on the Database tab of the New dialog box creates objects
that facilitate control of database synchronization from a PowerBuilder
application.</p>
<A NAME="TI4511"></A><p>This section describes the MobiLink synchronization wizard
and the objects it creates. For more detailed information about
synchronization from PowerBuilder applications, including information
about creating consolidated and remote databases, as well as synchronization
objects without using the wizard, see the chapter on MobiLink synchronization
in <i>Application Techniques</i>
.</p>
<A NAME="TI4512"></A><h2>What the wizard generates</h2>
<A NAME="TI4513"></A><p>You use the ASA MobiLink
Synchronization wizard to create a nonvisual user object and a global
external function that invokes the MobiLink <b>dbmlsync</b> executable.
By default, the wizard also adds two windows and a second global function,
but these objects are optional. </p>
<A NAME="TI4514"></A><p>The wizard-generated objects make it easier to add database
synchronization capabilities to a PowerBuilder target. A structure
that inherits from the PowerBuilder SyncParm object is also instantiated
by default by one of the wizard-generated global functions. The
SyncParm structure is used to hold sensitive database connection
parameters entered by an end user in the synchronization options
window.</p>
<A NAME="TI4515"></A><p><A HREF="pbugp149.htm#BDCJAJBE">Table 16-7</A> shows
objects that can be generated by the wizard, listed by their default
names, where <i>appname</i> stands for the name of
the current application.</p>
<A NAME="BDCJAJBE"></A><table cellspacing=0 cellpadding=6 border=1 frame="void" rules="all"><caption>Table 16-7: Objects generated by MobiLink
Synchronization wizard</caption>
<tr><th  rowspan="1"  ><A NAME="TI4516"></A>Default name</th>
<th  rowspan="1"  ><A NAME="TI4517"></A>Description</th>
</tr>
<tr><td  rowspan="1"  ><A NAME="TI4518"></A>nvo_<i>appname</i>_mlsync</td>
<td  rowspan="1"  ><A NAME="TI4519"></A>An instance of the MLSync standard class
user object that starts synchronization from the remote client. </td>
</tr>
<tr><td  rowspan="1"  ><A NAME="TI4520"></A>gf_<i>appname</i>_sync</td>
<td  rowspan="1"  ><A NAME="TI4521"></A>Global function that instantiates nvo_<i>appname</i>_mlsync
to start the synchronization. This function includes the logic to
start the synchronization with or without a feedback window.</td>
</tr>
<tr><td  rowspan="1"  ><A NAME="TI4522"></A>w_<i>appname</i>_syncprogress</td>
<td  rowspan="1"  ><A NAME="TI4523"></A>Optional feedback window that can be
used to display synchronization status to the client.</td>
</tr>
<tr><td  rowspan="1"  ><A NAME="TI4524"></A>gf_<i>appname</i>_configure_sync</td>
<td  rowspan="1"  ><A NAME="TI4525"></A>Optional global function that calls the w_<i>appname</i>_sync_options
window, which allows the user to configure the dbmlsync client before invoking
the dbmlsync executable.</td>
</tr>
<tr><td  rowspan="1"  ><A NAME="TI4526"></A>w_<i>appname</i>_sync_options</td>
<td  rowspan="1"  ><A NAME="TI4527"></A>Window that allows the application user
to change connection arguments at runtime. </td>
</tr>
</table>
<A NAME="TI4528"></A><h4>Using a desktop database profile</h4>
<A NAME="TI4529"></A><p>Some information that you enter in the wizard is optional,
but other information is required. The wizard prompts you for a
database profile, which it uses to establish a connection to a remote
database on the development computer. If you are not testing a connection
on the desktop, you can select the option to proceed without a database
connection and ignore the database profile field. </p>
<A NAME="TI4530"></A><p>A database profile is required for automatic retrieval of
publication names in the database. A publication is a database object
describing data to be synchronized. A publication, along with a
synchronization user name and a synchronization subscription, is
required for MobiLink synchronization. </p>
<A NAME="TI4531"></A><h4>Selecting publication names</h4>
<A NAME="TI4532"></A><p>The wizard lets you select multiple publication names if they
exist in the remote database defined by the connection profile.
There must be subscriptions associated with the publication in order
for them to display in the publication selection list.</p>
<A NAME="TI4533"></A><p>If you selected the option to proceed without a database connection,
the wizard prompts you to type a publication name (or a comma-separated
list of publication names) in the MobiLink Client Publication wizard
page instead of prompting you to select publication names retrieved
from the database.</p>
<A NAME="TI4534"></A><p>For more information about publications, see <i>MobiLink
- Client Administration</i>
 on the Technical Library CD or
the <ACRONYM title = "sequel" >SQL</ACRONYM> Anywhere online Help.</p>
<A NAME="TI4535"></A><h4>Overriding registry settings on the client computer</h4>
<A NAME="TI4536"></A><p>By default, information you enter in the wizard is saved in
properties of the nvo_<i>appname</i>_mlsync
user object that the wizard generates. This information includes
values that you select for MobiLink logging and command line options
and the MobiLink server and port. Prior to synchronization, the
values of these properties can be modified with values entered by
an application user in the w_<i>appname</i>_sync_options
Options window. </p>
<A NAME="TI4537"></A><p>The first time synchronization is run, user object property
values are entered into the client computer registry. The next time
the application is run, this information is available for retrieval
from the registry. </p>
<A NAME="TI4538"></A><p>The ASA MobiLink Synchronization wizard has an optional Override
Registry Settings screen that allows you to override client registry
settings. When you enable runtime overrides to the client registry
settings, you must assign a build number to the objects generated
by the wizard. </p>
<A NAME="TI4539"></A><p>The build number you assign can be any positive numeric value.
To override the registry settings, the build number you assign must
be higher than the build number in the registry, if there is one.
Registry settings will be used if the build number in the registry
is equal to or lower than the build number in the ObjectRevision
property of the nvo_<i>appname</i>_mlsync
user object that the wizard generates. </p>
<p><img src="images/note.gif" width=17 height=17 border=0 align="bottom" alt="Note"> <span class=shaded>Security measure</span> <A NAME="TI4540"></A>For security reasons, the MobiLink user name and password,
and the authentication parameters and encryption key database settings
are never saved to the registry.</p>
<A NAME="TI4541"></A><p>The Override Registry Settings page of the wizard displays
only if you do not change the radio button option to prompt the
application user for password and runtime changes on the previous
wizard page (Optional Runtime Configuration Objects). If, however,
you change the radio button selection to disallow runtime overrides
to the synchronization, the wizard does not display the Override
Registry Settings page and does not generate the w_<i>appname</i>_sync_options Options
window. </p>
<A NAME="TI4542"></A><h2>Wizard options</h2>
<A NAME="TI4543"></A><p>Except for the object name settings, <A HREF="pbugp149.htm#BDCGBFCA">Table 16-8</A> lists the ASA MobiLink Synchronization
wizard options. </p>
<A NAME="BDCGBFCA"></A><table cellspacing=0 cellpadding=6 border=1 frame="void" rules="all"><caption>Table 16-8: ASA MobiLink Synchronization
wizard options</caption>
<tr><th  rowspan="1"  ><A NAME="TI4544"></A>Option</th>
<th  rowspan="1"  ><A NAME="TI4545"></A>Description</th>
</tr>
<tr><td  rowspan="1"  ><A NAME="TI4546"></A>Destination library</td>
<td  rowspan="1"  ><A NAME="TI4547"></A>Lets you select the target <ACRONYM title = "pibble" >PBL</ACRONYM> file where you want to generate
the MobiLink synchronization objects.</td>
</tr>
<tr><td  rowspan="1"  ><A NAME="TI4548"></A>Desktop database connection</td>
<td  rowspan="1"  ><A NAME="TI4549"></A>Lets you select a PowerBuilder database
profile or proceed without a database connection.</td>
</tr>
<tr><td  rowspan="1"  ><A NAME="TI4550"></A>Publication name</td>
<td  rowspan="1"  ><A NAME="TI4551"></A>Lets you select a publication (or multiple
publications) if you specified a database profile for a desktop
database connection. If you did not, you can type the name of a publication
you want to synchronize.</td>
</tr>
<tr><td  rowspan="1"  ><A NAME="TI4552"></A>Override registry settings</td>
<td  rowspan="1"  ><A NAME="TI4553"></A>Lets you override client registry settings
with values that you (or application users) select for MobiLink
logging and command line options, and the MobiLink server and port
for the application</td>
</tr>
<tr><td  rowspan="1"  ><A NAME="TI4554"></A>Client logging options</td>
<td  rowspan="1"  ><A NAME="TI4555"></A>Specifies what information gets written
to the synchronization log and whether you save the information
to a log file.</td>
</tr>
<tr><td  rowspan="1"  ><A NAME="TI4556"></A>Additional command line options</td>
<td  rowspan="1"  ><A NAME="TI4557"></A>Adds the options you specify to the command
line for starting the MobiLink synchronization client. You can click
the Usage button to see a list of valid options.</td>
</tr>
<tr><td  rowspan="1"  ><A NAME="TI4558"></A>Extended options</td>
<td  rowspan="1"  ><A NAME="TI4559"></A>Adds extended options you specify. You
do not need to enter the "-e" switch for extended
options in this field. You can click the Usage button to see a list
of valid extended options.<A NAME="TI4560"></A><p>Single quotes must be used for any extended option values
requiring quotation marks. You must separate multiple options with
semicolons; for example: <p><PRE> scn=on;adr='host=localhost;port=2439'</PRE></p></td>
</tr>
<tr><td  rowspan="1"  ><A NAME="TI4561"></A>Host</td>
<td  rowspan="1"  ><A NAME="TI4562"></A>Sets the host information for connecting
to the MobiLink synchronization server. If you enter a value for
this field, it overrides any value set in synchronization subscriptions
and in the Extended Options field.</td>
</tr>
<tr><td  rowspan="1"  ><A NAME="TI4563"></A>Port</td>
<td  rowspan="1"  ><A NAME="TI4564"></A>Sets the port for connecting to the MobiLink synchronization
server. The default port for MobiLink is 2439. The value you enter
for this field overrides any value set in synchronization subscriptions
and in the Extended Options field.</td>
</tr>
</table>
<A NAME="TI4565"></A><h2>Trying out MobiLink synchronization </h2>
<A NAME="TI4566"></A><p>This section describes how to try out the ASA MobiLink Synchronization wizard
in a sample application. To get started, create a new workspace
and a template application. You do not need to create a <ACRONYM title = "sequel" >SQL</ACRONYM> database connection, but you
do need to create a project.</p>
<A NAME="TI4567"></A><p>Before you use the wizard to generate objects for the application,
you need to set up a remote database and add at least one publication,
user, and subscription to it, and create a PowerBuilder database
profile for the remote database. To test the synchronization objects
from your application, you need to set up a consolidated database.
You can create your own remote and consolidated databases, as described
in the chapter on MobiLink synchronization in <i>Application
Techniques</i>
.</p>
<A NAME="TI4568"></A><p>To test the synchronization objects, complete the following
steps:<A NAME="TI4569"></A>
<ol>
</li>
<li class=ds><A HREF="pbugp149.htm#BCGGCCEA">Run the wizard</A>.</li>
<li class=ds><A HREF="pbugp149.htm#BCGDIHDA">Call synchronization objects
from your application</A>.</li>
<li class=ds><A HREF="pbugp149.htm#BCGEECII">Deploy the application and
database files</A>.</li>
<li class=ds><A HREF="pbugp149.htm#BCGJFIHE">Start the MobiLink server</A>.</li>
<li class=ds><A HREF="pbugp149.htm#BCGFABBB">Run the application</A>.
</li>
</ol>
</p>
<A NAME="BCGGCCEA"></A><h4>Run the wizard</h4>
<A NAME="TI4570"></A><p>You start the wizard from the Database tab of the New dialog
box. The wizard prompts you for a database profile and a publication,
although you can enter this information at a later time after you
generate synchronization objects. </p>
<A NAME="TI4571"></A><p><img src="images/proc.gif" width=17 height=17 border=0 align="bottom" alt="Steps"> To run the MobiLink synchronization wizard</p>
<ol><li class=fi><p>Select File&gt;New from the PowerBuilder menu
bar.</p></li>
<li class=ds><p>Click the Database tab, select the ASA MobiLink
Synchronization wizard, and click OK.</p></li>
<li class=ds><p>Follow the instructions in the wizard, providing
the information the wizard needs.</p><p>For help using the wizard, place the mouse pointer in any
wizard field and press F1.</p><p>On the last page of the wizard, make sure the Generate To-Do
List check box is selected if you want the wizard to add items to
the To-Do List to guide and facilitate your development work. </p></li>
<li class=ds><p>When you are satisfied with your choices in the
wizard, click Finish.</p><p>The wizard generates objects that you can use for database synchronization.</p></li></ol>
<br><A NAME="BCGDIHDA"></A><h4>Call synchronization objects
from your application</h4>
<A NAME="TI4572"></A><p>Open a menu for your application in the Menu painter and add
two submenu items to the File menu, called <b>Synchronize</b> and <b>Sync
Options</b>. Add the following code to the Clicked event
of the <b>Synchronize</b> menu item (<i>appname</i> is
the name of your application):<p><PRE> syncparm s_opt<br>gf_<i>appname</i>_sync(s_opt)</PRE></p>
<A NAME="TI4573"></A><p>Add the following code to the Clicked event of the Sync Options
menu item:<p><PRE> gf_<i>appname</i>_configure_sync()</PRE></p>
<A NAME="BCGEECII"></A><h4>Deploy the application and
database files</h4>
<A NAME="TI4574"></A><p>Use the Project painter to deploy the application to the desktop
and copy this to all computers that will be connecting remotely
to the MobiLink server. You need to copy the remote database to
all end-user computers, and either register the database as an ODBC
database or include connection parameters in a data source name
(DSN) file<i></i>.</p>
<A NAME="TI4575"></A><p>For information on additional files and registry entries required
on end-user computers, see the chapter on MobiLink synchronization
in <i>Application Techniques</i>
.</p>
<A NAME="BCGJFIHE"></A><h4>Start the MobiLink server</h4>
<A NAME="TI4576"></A><p>Select MobiLink Synchronization Server from the Utilities
folder in the Database painter. Fill in the required information
and click OK to start the server.</p>
<A NAME="TI4577"></A><p>For more information, see <A HREF="pbugp150.htm#BDCHGCAJ">"Starting the MobiLink synchronization
server"</A>.</p>
<A NAME="BCGFABBB"></A><h4>Run the application</h4>
<A NAME="TI4578"></A><p>Run the application on the remote computer and select the
File&gt;Synchronize and File&gt;Sync Options menu items
to test their operation.</p>

